Micron Document
Fox's Git Mirrors

Node / rns-mirrors / Reticulum-Go.git / commits / 83609bc

Commit 83609bcb589eb3cfc35b98ecc0b3327b2ae99d77

🗀 Browse tree at this commit

Parents : da19042
Author : Ivan <e318cbc04468bd574db2b4523dddd710>
Signature : T66BB85Valid, signed by author
Date : 2026-08-14T19:20:59-05:00

docs: update documentation for 'reticulum-go zen' command and related utilities

Changes

8 files changed, 77 insertions(+), 5 deletions(-)

M docs/en/README.md +1 -1
M docs/en/api-reference.md +2
M docs/en/compatibility.md +1
M docs/en/development-and-testing.md +15
M docs/en/links-channels-and-resources.md +1 -1
M docs/en/package-map.md +11 -1
M docs/en/utilities.md +46 -2
R reticulum-go.rsm

Diff

diff --git a/docs/en/README.md b/docs/en/README.md
index 49cf0033..58a8b51c 100644
--- a/docs/en/README.md
+++ b/docs/en/README.md
@@ -27,7 +27,7 @@ Documentation is organized by language under `docs/`. English lives in `docs/en/
| [Compatibility](compatibility.md) | Parity with Python RNS, gaps, Go-only extensions |
| [Control API](control-api.md) | Localhost JSON and WebSocket API for non-Go clients, Dart and Flutter |
| [librns](librns.md) | C ABI map, supported surface, events, build and smoke, Odin bindings |
-| [CLI utilities](utilities.md) | `reticulum-go` subcommands (status, slow, id, probe, path, cp, pageserver), shared-instance RPC with Python |
+| [CLI utilities](utilities.md) | `reticulum-go` subcommands (status, slow, zen, id, probe, path, cp, pageserver), shared-instance RPC with Python |
| [Embedding and WebAssembly](embedding-and-wasm.md) | `pkg/node`, WASM, browser integration |
| [Firecracker microvm](microvm.md) | Guest rootfs, VSOCK host bridge, nested VM networking |
| [Development and testing](development-and-testing.md) | Code quality, crossref tests, interop tests, CI |

diff --git a/docs/en/api-reference.md b/docs/en/api-reference.md
index 23b088a3..de1648d9 100644
--- a/docs/en/api-reference.md
+++ b/docs/en/api-reference.md
@@ -172,6 +172,8 @@ Do not wait a flat 15 seconds for a path or link. `AwaitPath` sizes the wait fro
Do not loop `RequestPath`, `Announce`, `Establish`, or `Request`. Repeats return `ErrPathRequestThrottled`, `ErrDestAnnounceThrottled`, `ErrLinkEstablishBusy` / `ErrLinkAlreadySettled`, or `ErrLinkRequestBusy` / `ErrLinkRequestDuplicate`. `RequestPath` with no ready outgoing interface returns `ErrTransportNoOutgoingForPR`. Wait on callbacks or `AwaitPath`.
+Run `reticulum-go zen` on your module to catch these patterns in source before they ship. See [CLI utilities](utilities.md#rgozen).
+
If you must use a timer around handshake, wait `l.EstablishmentTimeout()` plus a small margin (`rnsutil.LinkEstablishmentWindow`).
## Recipe: send a file resource

diff --git a/docs/en/compatibility.md b/docs/en/compatibility.md
index 4752a92c..b2a2c717 100644
--- a/docs/en/compatibility.md
+++ b/docs/en/compatibility.md
@@ -154,6 +154,7 @@ These do not change the wire format:
| rnsd | `reticulum-go` daemon |
| rnstatus | rgostatus (same RPC and remote `-R` dest as Python, extra Go integrity fields) |
| (none) | rgoslow / `reticulum-go slow` (bottleneck and local health findings, Go-only) |
+| (none) | rgozen / `reticulum-go zen` (static path and link footgun scan for Go and optional Python, Go-only) |
| `Examples/Speedtest.py` | rgospeed / `reticulum-go speedtest` (loopback link throughput smoke) |
| rnid | rgoid (`.rid`/`.rsg`/`.rsm`/`.rfe` compatible) |
| rnprobe | rgoprobe |

diff --git a/docs/en/development-and-testing.md b/docs/en/development-and-testing.md
index 792ae56d..e0b9856d 100644
--- a/docs/en/development-and-testing.md
+++ b/docs/en/development-and-testing.md
@@ -352,6 +352,21 @@ CI runs self-check on Linux (amd64 and arm64), macOS, Windows, FreeBSD, and Open
NetBSD is not in CI. Run `reticulum-go self-check` manually on that host.
+### Static footgun scan
+
+`reticulum-go zen` scans Go sources (and optional Python with `-python`) for path and link anti-patterns: RequestPath or HasPath loops, Establish before AwaitPath, link use without callbacks, announce bursts, and legacy 15 second timeouts. It is a developer tool, not a runtime check. No daemon is required.
+
+```bash
+make build
+./bin/reticulum-go zen ./...
+./bin/reticulum-go zen -list-rules
+./bin/reticulum-go zen -fix ./pkg/myapp/...
+```
+
+`-fix` applies only safe edits (checking RequestPath errors in functions that return error). Warnings without `-fix` exit non-zero so CI can gate on the scan.
+
+Package tests live in `pkg/zenfix/`. Full flag and rule reference: [CLI utilities](utilities.md#rgozen).
+
## Vendoring
Ordinary builds use vendored modules. Refresh after dependency changes:

diff --git a/docs/en/links-channels-and-resources.md b/docs/en/links-channels-and-resources.md
index 580d766f..0023ad1c 100644
--- a/docs/en/links-channels-and-resources.md
+++ b/docs/en/links-channels-and-resources.md
@@ -138,7 +138,7 @@ Python 1.3.2 tears down links at LINKIDENTIFY when the remote identity is blackh
**One link per peer session.** Multiplex logical streams with channel or buffer instead of opening redundant links.
-**Wait with the stack, not a flat timer.** Outbound links need a path. Call `Transport.AwaitPath` (or send Control API `link.open` / librns `LinkOpen`) so the wait follows interface bitrate. Do not sleep 15 seconds.
+**Wait with the stack, not a flat timer.** Outbound links need a path. Call `Transport.AwaitPath` (or send Control API `link.open` / librns `LinkOpen`) so the wait follows interface bitrate. Do not sleep 15 seconds. `reticulum-go zen` flags these patterns in application code.
**Resource size.** Respect MTU and part sizing. Large files use many parts over the same link.

diff --git a/docs/en/package-map.md b/docs/en/package-map.md
index bdedff35..9072ce64 100644
--- a/docs/en/package-map.md
+++ b/docs/en/package-map.md
@@ -194,13 +194,23 @@ Python share_instance equivalent.
### `pkg/cli`
-Subcommand dispatch for the unified `reticulum-go` binary (Main, RunStatus, RunID, RunProbe, RunPath, RunCP, RunPageserver).
+Subcommand dispatch for the unified `reticulum-go` binary (Main, RunStatus, RunID, RunProbe, RunPath, RunCP, RunPageserver, RunZen).
| Item | Detail |
|------|--------|
| Entry | `Main(opts)` from `cmd/reticulum-go` |
| Docs | [CLI utilities](utilities.md) |
+### `pkg/zenfix`
+
+Static analyzer for path and link footguns. Used by `reticulum-go zen`.
+
+| Item | Detail |
+|------|--------|
+| Entry | `zenfix.Run(opts)` |
+| Rules | `AllRules` in `rules.go`, checkers in `analyze.go` / `python.go` |
+| Docs | [CLI utilities](utilities.md#rgozen), [Development and testing](development-and-testing.md#static-footgun-scan) |
+
### `pkg/pageserver`
NomadNet-style page and file server used by `reticulum-go pageserver`.

diff --git a/docs/en/utilities.md b/docs/en/utilities.md
index 7a55e2c5..1b29c162 100644
--- a/docs/en/utilities.md
+++ b/docs/en/utilities.md
@@ -16,7 +16,7 @@ make build
./bin/reticulum-go pageserver
```
-`make install` also creates legacy symlinks (rgostatus, rgoid, rgoprobe, rgopath, rgocp, rgox, rnx, rgosh, rgopageserver, rgoslow, rgospeed, rgodump, rgosnap, rgoselfcheck) that invoke the same binary. Man pages: man reticulum-go, man reticulum-go-status, man reticulum-go-speedtest, man reticulum-go-self-check, and so on.
+`make install` also creates legacy symlinks (rgostatus, rgoid, rgoprobe, rgopath, rgocp, rgox, rnx, rgosh, rgopageserver, rgoslow, rgospeed, rgodump, rgosnap, rgoselfcheck, rgozen) that invoke the same binary. Man pages: man reticulum-go, man reticulum-go-status, man reticulum-go-speedtest, man reticulum-go-self-check, and so on.
| Tool / subcommand | Python counterpart | Role |
|-------------------|--------------------|------|
@@ -30,6 +30,7 @@ make build
| `reticulum-go sh` (rgosh) | rnsh (native + auto rnsh) | Interactive remote shell over Link+Channel (PTY/pipes) |
| `reticulum-go pageserver` | (example app) | NomadNet-style page and file server |
| `reticulum-go self-check` (rgoselfcheck) | (Go-only) | Host OS preflight for sandbox, crypto, and interfaces |
+| `reticulum-go zen` (rgozen) | (Go-only) | Static scan for path and link footguns in Go and optional Python sources |
| `reticulum-go speedtest` (rgospeed) | `Examples/Speedtest.py` | Loopback smoke plus cross-host / docker daemon (`-daemon`, `-iface`) |
| `reticulum-go dump` (rgodump) | (Go-only) | Decode RNS packets from hex or pcap to JSONL |
| `reticulum-go snapshot` (rgosnap) | (Go-only) | Path table, links, and health drop counters as JSON |
@@ -54,7 +55,7 @@ Python utilities and Go subcommands speak the same destinations, shared-instance
| Shell on dest app `rnsh` | rnsh | `reticulum-go sh` (auto) | Yes | Yes (Go listener announces `rnsh` as well) |
| Shell on dest app `rgosh` | (no) | `reticulum-go sh` | n/a | Go native only |
-Remote drop, path-request, and blackhole mutate over `-R` exit 255 on both stacks. rnir, rnpkg, rngit, and rnodeconf stay Python-only. rgoslow, rgodump, rgosnap, and rgoselfcheck stay Go-only.
+Remote drop, path-request, and blackhole mutate over `-R` exit 255 on both stacks. rnir, rnpkg, rngit, and rnodeconf stay Python-only. rgoslow, rgodump, rgosnap, rgoselfcheck, and rgozen stay Go-only.
## Shared-instance RPC (required for rgostatus and rgopath table modes)
@@ -456,6 +457,48 @@ RUN_LIVE_INTEROP=1 PYTHON_INTEROP=python3 RETICULUM_PATH=/path/to/reticulum \
go test -v ./tests/interop/ -run 'Rgosh|Rnsh'
```
+## rgozen
+
+```bash
+reticulum-go zen [flags] [packages...]
+# legacy: rgozen
+```
+
+Static source checker for Reticulum path and link footguns. Think go vet or go fix for common mistakes that lead to throttling, handshake storms, or path resolved but link never opens. No daemon or network access is required.
+
+Default scan is `./...` from the current module. Pass package patterns the same way as go test.
+
+| Flag | Meaning |
+|------|---------|
+| `-fix` | Apply safe automatic fixes (today: check RequestPath errors in functions that return error) |
+| `-json` | Emit a JSON report |
+| `-list-rules` | Print all rule IDs, severity, and hints, then exit |
+| `-plain` | Plain output without colors |
+| `-test` | Include `*_test.go` files |
+| `-python` | Also scan `.py` files under the module root |
+| `-C dir` | Module root directory (default: cwd) |
+
+Exit code is 0 when clean, 1 when errors are present or warnings remain without `-fix`, 2 on flag errors.
+
+### What it catches
+
+Go rules cover spinning on RequestPath, HasPath, or AwaitPath, Establish or NewLink inside loops, link use before the established callback, announce bursts, hard-coded 15 second timeouts, RequestPath with on_interface overrides, and Recall before a path wait.
+
+With `-python`, the same anti-patterns are checked in RNS Python apps: has_path and request_path loops, await_path inside retry loops, link_ready and link.status polling, request_path followed by has_path spin, Recall before await_path, on_interface overrides, and require_shared_instance without a running rnsd.
+
+Each finding prints file, line, rule ID, why it fails, a fix hint, and doc references. Run `-list-rules` for the full catalog.
+
+Example:
+
+```bash
+reticulum-go zen ./pkg/myapp/...
+reticulum-go zen -python -C ~/my-rns-app
+reticulum-go zen -fix ./...
+reticulum-go zen -json ./pkg/... | jq .
+```
+
+Use this during development and in CI before shipping apps that talk to shared instances or slow radios. See also [API reference](api-reference.md) path and link guidance and [Development and testing](development-and-testing.md#static-footgun-scan).
+
## Troubleshooting
| Symptom | Fix |
@@ -477,6 +520,7 @@ RUN_LIVE_INTEROP=1 PYTHON_INTEROP=python3 RETICULUM_PATH=/path/to/reticulum \
| `reticulum-go path -t` | Path table dump |
| `reticulum-go debug` | Effective config path, log level, platform, RPC reachability (`-rates`, `-json`) |
| `reticulum-go self-check` | Host OS preflight checklist (`--json`, `--quick`, `--full`, `--strict`) |
+| `reticulum-go zen` | Static path and link footgun scan (`-fix`, `-json`, `-list-rules`, `-python`) |
| `reticulum-go probe` | Connectivity / RTT (`-json`) |
| Control API | HTTP `/v1/health` (liveness), `/v1/status` (iface stats plus integrity fields), `/v1/paths` when `enable_control_api = yes` |
| Daemon `-debug N` | Override config loglevel for one run |

diff --git a/reticulum-go.rsm b/reticulum-go.rsm
index 680bdf73..833982a5 100644
Binary files a/reticulum-go.rsm and b/reticulum-go.rsm differ

Served by rngit 1.5.2 - Generated in 0.06s